Maintaining Program Understanding -- Issues, Tools, and Future Directions

The understanding of a program is a key aspect of software development. The understanding is a prerequisite for the initial development efforts. This paper is concerned with the challenge of maintaining the program understanding with the purpose of supporting later phases in the program life time. One approach to maintaining program understanding is to document decision and rationales behind a program as informal textual explanations— internal documentation. The starting point of this paper is a particular paradigm for program documentation program called Elucidative Programming. As the first contribution of this paper, three key documentation issues are identified on the basis of the experience with Elucidative Programming. Documentation motifs represent thematic elements of software, which typically transverse the structure of the source program files. Documentation proximity characterizes the distance between the documentation and the program. Documentation occasions are temporally situations for capturing and formulating the understanding of the program. During the years a large number of documentation tools have been developed. As the second contribution of the paper, a number of contemporary documentation tools are reviewed. The tools are selected on basis of relevance for the key documentation issues, and relative to the common attention and interest of the particular tool in the documentation communities. As the final contribution, and as a conclusion of the paper, a number of future directions and challenges are outlined.